The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/programm.ing/szadb1_4.zoo/doc/lpr/szadb.doc

Text File | 1991-07-08 | 19.3 KB | 521 lines

NAME

    szadb - Sozobon debugger, version 1.4

USAGE

    szadb [[-nc] [-nb] [-k defs] [-om] [-os]] program [args]

where 'args' is an optional command line to be passed to 'program'.

SUMMARY

Szadb is a machine language debugger with symbols which is similar to
the old UNIX 'adb' command.  Szadb is used to control and monitor
another program.  This program is loaded into memory and relocated
when szadb is first started.  Commands to szadb allow the user to
examine and modify memory and machine registers, single step and set
breakpoints.  Szadb was written as a companion debugger for Sozobon C
compiler, but it can be used with other compilers which can produce a
symbol table in the same format (Alcyon C, ST version of gcc with
small modifications - c.f. "Primer" for details).  Version 1.2 also
understands symbols created by Mark Williams C and attempts to adjust
itself to this format automatically.  Use options -om and -os if the
debugger got confused.  Version 1.3 adds a support for long symbols
names in "GST format" which are produced by newer versions of gcc
loader when -G flag is used.  Version 1.4 frees szadb from hardwired
screen parameters which allows for use on TT in all screen
resolutions.  This does not mean yet a support for non-68000
instructions.  This would be pretty easy to add but is left for a
person or persons with TT and necessary MC68020/30 references on hand.
Version 1.4 allows also a use of szadb with Moniterm, but this
requires an additional ST monitor connected in parallel, due to a way
in which Moniterm driver operates.  Check details in "Primer".

OPTIONS

    -nc  disallow commands stored with breakpoints; saves some
         memory

    -nb  turn off buffering of output which goes to a trancript
         file; saves memory but a usage of '$>file' request is
         then not recommended

    -k   the following argument is a name of a file with function
         key definitions; see FUNCTION KEYS for details.

    -om  'program' is an executable in MWC format

    -os  'program' is an executable in Sozobon C format


WINDOWS

Szadb uses its own window or screen.  Thus commands and output will
not interfere with the program's window.  In fact, szadb does output
without using the BIOS so as not to confuse the program's cursor.

Use <cntl-w> to view the program's screen when you are in the szadb
window.  Type another character to get back.


ONLINE HELP

A summary of this manual is available by typing the 'help' key.  Use 'q'
to get back to the szadb prompt.  Typing any other key will advance to the
next help screen.

People in other countries are encouraged to come up with versions of szadb
with the messages in their language.  You should only have to change the one
file "lang.h".


SYNTAX

In the following description of commands, certain syntactic abbreviations
are used.

    {expr}   - any valid expression consisting of numbers, symbols and
           operators.  See the section on EXPRESSIONS
       ,{count}  - a repeat count for the command.  Can be any expression
    {format} - a string of characters which specifies how values are
           printed. See the section on FORMATS
    {args}     - The arguments or parameters to be passed to the program
    {value}  - an additional expression used by the command
    {line}     - any string which will fit on a command line

FORMAT OF COMMANDS

The general format for command X is

    {expr},{count}X            for most commands
or    {expr},{count}X{format}        for / or ? or =
or    {expr},{count}X{args}        for :c
or    {expr},{count}X{value}        for /w or /W
or    {expr},{count}X{line}        for :b, :s, :n, :f

Spaces and tabs can be input to improve readability.  They are always
ignored.

All fields are optional.  If {count} is missing, we do the command once.
If {format} is missing we re-use the last {format}.  If {args} are missing,
no parameters are passed.  If {values} are missing, nothing is written.
There could be multiple commands on one input line if they are
separated by semicolon ';'.

Any string will be accepted as an argument {line} which occurs in a format
for :b, :s, :n, and :f.  Stepping commands with non-empty argument do not
step through any program instructions.  If -nc option is not used then the
string {line} will be stored and later szadb will attempt to execute it when
a breakpoint is hit or a stepping command with an empty argument is be
called.  The user is solely responsible for makine a {line} into a string
of valid szadb requests if (s)he wants to anything else but an error
message.  Setting the same breakpoint or calling stepping command with a
new argument will replace the stored line with a new one.

If {expr} is missing, we use the value of DOT.  DOT is set to the PC after
we single step or hit a breakpoint.  DOT is set to {expr} by most commands.
DOT is set to the next address after locations that were printed by
the / or ? command.

If the command is missing, we use the last command.  Thus an empty line
repeats the last command with DOT for the {expr} and 1 for the {count}
(and {format} the same as before).


THE ':' GROUP

    :s or :S

    This command is used to single step the program.  It will use the
    trace bit of the 68000 to force a trap after one instruction.
    We do not switch to the program window for single stepping.

    :c or :C

    This command is used to continue the program.  We will switch to
    the program window and run at full speed until a breakpoint is
    hit, a trap occurs or the program exits.

    :n or :N

    Like :s, but the program does not descend into subroutines.
    The command :c is used when a subroutine call encountered with
    an automatic stop upon return to the caller.  If any breakpoints
    were set inside of such subroutine they wll be obeyed.

    :j or :J

    A version of :n which will skip the next instruction if it is
    a branch.  It reverts automatically to :n for purposes of
    autorepeating.  An argument accepted will be also these one
    for :n.  There is no check if an instructions which follows
    a skipped branch can be actually reached.

    :f or :F

    Execute all command in the current subroutine and stop upon
    return to the caller.  Any breakpoints found will be obeyed.

    The upper case versions of each command print all the machine
    registers after running the program.

    If parameters of the program were not passed on a command
    line then can be specified as a string {args} which follows
    the first :c  executed in a debugging session.

    If an {expr} field is given to the :c or :s, the PC is set to
    that value.  This should be used with care!

    :b  -  set a breakpoint at {expr}
    :d  -  delete the breakpoint at {expr}
    ::  -  control execution of commands attached to :b, :s, :n or :f;
           see EXECUTION CONTROL

Note that the only way to re-start the program is to exit szadb and start
over.

THE '$' GROUP

    $q    - quit szadb
    $r    - print all register values
    $e    - print all external symbols and their values
          This display will stop at the bottom of every screen and
          will wait for a keypress.  Keys 'q', 'Q' and ctrl-C will
          terminate, any other key will continue.  Printing is done
          when you will see back szadb prompt '> '.
    $o    - use octal numbers
    $x    - use hex numbers
    $d    - use decimal numbers
      $s    - set the maximum symbol offset to {expr}
          When address are printed by szadb, they are printed as
          symbol+offset if offset is <= to this value
    $b    - print all breakpoints with their optional commands
              and print active commands attached to stepping requests
    $c    - print a stack backtrace
    $C    - print a stack backtrace with arguments
          If szadb cannot determine the number of arguments
          (because there were none or because the optimizer was used),
          it prints the location on the stack where they might be
    $p    - print the basepage of the program
    $><nam> - append all szadb output to a transcript file named '<nam>'
          If a string '<nam>' is empty or different from the previosly
          used then flush output buffers and close the transcript;
          open a new one with a new name if '<nam>' non-empty.
          Transcript output is internally buffered by default
          unless -nb option is used.
    $k    - display all function key definitions
    $k<num> - if <num> is a decimal number between 1 and 20 execute
          an associated function key definition as a sequence of
          szadb commands


THE '/' or '?' GROUP

UNIX adb uses '?' to examine a program file and '/' to look at running
process's memory.  Since szadb only looks at memory, either can be used.
We recommend using '/' since later versions of szadb may use '?' for files.

    /

    Print values from memory according to a format.  See FORMATS.
    {expr} gives the starting address to fetch values from.
    If there is more than one format character, we increment the
    address used by the size of the value printed.

    /w    - Write a 2-byte value to memory at address {expr}
    /W    - Write a 4-byte value to memory at address {expr}

THE '=' COMMAND

    =

    Print the value of {expr} according to a format.  See FORMATS.
    If there is more than one format character, we print the same
    value each time.

THE '>' GROUP

Register values can be changed using '>' followed by the register name.
This sets that register to the value of {expr}.  See REGISTER NAMES

THE '<' GROUP

Register or a special variable value can be retrieved using '>' followed
by the register or variable name.  See REGISTER NAMES and SPECIAL VARIABLES


FORMATS

Formats are similar to printf() format strings.  They specify the way
values are printed.  However, since we almost always want to print a
value and not some literal string, the '%' before each format is missing.
Also, we usually use upper case for long values instead of a leading 'l'.
Thus %d%lx%o becomes dXo.

    d  - print 2-bytes as decimal
    D  - print 4-bytes as decimal
    x  - print 2-bytes as hex
    X  - print 4-bytes as hex
    o  - print 2-bytes as octal
    O  - print 4-bytes as octal
    c  - print a single character
    b  - print 1-byte as octal
    s  - print a string

In addition, we add the following non-printf-like formats:

    i  - print a single machine language instruction
    S  - print a string with '.' for special characters
    p  - print the current value of DOT as a symbol plus offset
    a  - same as p except also print a ':' and tab
    r  - print a space
    n  - print a newline
    t  - tab to the next tab stop of a given width (see below)
 "string"  - print a literal string
    +  - increment DOT (nothing printed)
    -  - decrement DOT (nothing printed)
    ^  - backup DOT by the last size printed

Formats can also be preceeded by a number in a current base.  This number
is usually the repeat count for the next format.  Thus instead of saying
main/iiiiXXXXXX you can say main/4i6X

The 't' format is always preceeded by a number.  This format advances to
the next tab stop which a multiple of that number.  For example, 8t moves
to the next 8-space tabstop.


EXPRESSIONS

    Expressions are a lot like C expressions.  They include numbers
and symbols with unary and binary operators.  Expressions are always
evaluated using long (4-byte) arithmetic.  Parenthesis can be used for
grouping.  There is no precedence among binary operators - evaluation is
strictly left to right.

    NUMBERS

    Numbers can be entered in any base.  A base is specified using one
of the following prefixes:

    0x - hex
    0t - decimal
    0o - octal

    If there is no such prefix, the default base will be used.  The
default base when you start szadb is hex.  Use a leading 0 if you need
to enter a hex number which starts with a letter.

    SYMBOLS

    If your program has a symbol table, these symbol names can be
used in expressions.  The value of a symbol is the address of that
variable or function.  Although the C compiler adds a leading '_' to
all symbols, the symbol name will be found with or without the '_'.

    OTHER VALUES

    Character literals can be entered by enclosing one to four
characters in single quotes.  Multi-character literals put the first
character in the highest byte.

    The value of DOT can be used in an expression by typing "."

    Use "&" to represent the last typed {expr} field.  (DOT
changes when you print with / or ?.  "&" does not.)

    UNARY OPERATORS

    -   unary minus (2-s complement)
    ~   bitwise complement (1-s complement)
    *   fetch of 4 bytes from an address
    @   fetch of 2 bytes from an address

    BINARY OPERATORS

    +   addition
    -   subtraction
    *   multiplication
    %   division (NOT '/' !)
    &   bitwise and
    |   bitwise or


REGISTER NAMES

Szadb uses the standard Motorola register names with 'sp' for 'a7'.
Actually, there are two stack pointers which Motorola calls 'usp' for
the user stack pointer and 'ssp' for the supervisor stack pointer.
Szadb calls the other stack pointer 'xsp'.  This will be 'ssp' if
your program is running in user mode (as it usually is) or 'usp' if
it is running in supervisor mode.


SPECIAL VARIABLES

Szadb provides four special read only variables which describe
a layout of the program in a memory.  They are

        l       lowest text address
        t       length of the text segment
        b       start of the bss segment
        d       length of the data segment



FUNCTION KEYS

Szadb recognizes twenty function keys with numbers from 1 to 20, where
first ten numbers correspond to markings on a keyboard and other denote
function keys pressed together with a "Shift" key.

One may optionally asign strings to functions keys by reading definitions
from a file which name follows -k argument to szadb.  Every definition
should start in the first column with an uppercase 'F' followed by a key
number and optional white space.  A trailing string will be stored as the
key definition.  Definitions can be continued on the following lines if
end-of-line character(s) are escaped with a '\' character.  All other
lines and attemps of redefinition of already defined keys will be ignored.
A maximal length of a definition is limited by quite generous (around
2K for this version).

When function key is pressed then as many characters from its definition
string as it will fit will be appended to teh current szadb input line.
The cursor will be put at the end and a resulting sequence of szadb
commands can be edited.

An entire definition of a function key can be execucuted by usind $k
request followed by a corresponding function key number (decimal).
A request $k by itself will display a list of all function key definitions.



EXECUTION CONTROL

Commands attached to :b and stepping commands :s, :n and :f can be
switched off and on without destroying a stored string.  A special form
{expr}::b- turns off executions of a string stored with a breakpoint
at an address {expr}.  To reverse that action use {expr}::b+.  A similar
form works also for stepping commands.

A request :f has a special default action attached.  When overtyped
or switched off can be always restored by a use of ::f` request.

Stepping commads :f and :n can also have their attached commands "shifted"
by a use of ::f_ and ::n_ requests.  This will cause for :f a switch
of attached command string to this for :n or :s (in that order) and for
:n a switch to a strig for :s.  This switch only takes place if
corresponding command strings are defined and active.  Requests
::n+, ::f+ or ::f` will restore an original actions.  Status of all
stepping commands is displayed after $b request.



SPECIAL CHARACTERS

When entering a command, use the left-arrow (backspace) to erase typed
characters.  When a lot of output is being printed, you can use cntl-S
to suspend output temporarily or cntl-C to stop the command.

Use the help key to get a summary of this document from within szadb.


MAGIC STUFF

Szadb works by changing the trap vectors to point to itself.  If you
try to debug any program which changes the trap vectors, szadb will not
work.

Breakpoints cannot be set on ROM locations, but szadb will not give you
an error if you try.

Various shells do funny things to parameters.  Szadb does not Upper-case
arguments and does not pass more than 128 bytes of parameters (but
see examples in "Primer" how to circumvent this limitation).

Programs compiled with the dLibs startup routine (e.g. most programs
compiled with Sozobon C) do funny things to try to determine argv[0].
In particular a pointer to the parent's basepage is followed.  Szadb
does not set up this pointer, so argv[0] is not passed under szadb.

Programs compiled with other compilers, or written in assembler, may use
different calling conventions and an organization of stack frames.
This may cause difficulties to requests like $c and :f.  Use your better
judgement.

Certain programs only work when loaded at a certain address (or only
fail when loaded at a certain address).  Running a program under szadb
changes where that program is loaded.  Thus behavior under szadb may
be different from what happens otherwise.

Programs with bugs may modify random locations of memory.  If they
happen to modify a value that is part of szadb, szadb will probably
die.  Unfortunately, this isn't UNIX.


SEE ALSO
    differs.doc, "SZADB Primer", the source

BUGS

Despite of a support for displays of different sizes a program input
buffer is fixed and will accept upto 78 characters from a keyboard.
This can be construed as a feature.

WHERE TO GET SOZOBON C

Sozobon C is freely distributed through many bulletin boards and computer
networks worldwide.  If you cannot find it anywhere locally, you can
always order the newest release from us directly.  Send $10 US to cover
shipping, handling and floppies (add a couple $ for European orders) to

        Tony Andrews
        5902E Gunbarrel Ave.
        Boulder, Colorado USA  80301

After March 30, 1990 this will change to

        Tony Andrews
        4704 Berkshire Court
        Boulder, Colorado USA  80301

Make checks payable to Tony Andrews.  Specify single or double sided
floppies (you will get double sided if you don't say anything).

If you don't need the release, but you want to encourage further product
development from Sozobon Ltd, we will gladly accept money, ST software
such as games you don't play anymore, freeware or shareware you have
written with Sozobon and/or simple words of encouragement.


LEGALESE

/* Copyright (c) 1990 by Sozobon, Limited.  Authors: Johann Ruegg, Don Dugger
 * Modifications for version 1.2(mj+ach): Anthony Howe, Michal Jaegermann
 * Version 1.4 with support for Moniterm and TT screens - Michal Jaegermann
 *
 * Permission is granted to anyone to use this software for any purpose
 * on any computer system, and to redistribute it freely, with the
 * following restrictions:
 * 1) No charge may be made other than reasonable charges for reproduction.
 * 2) Modified versions must be clearly marked as such.
 * 3) The authors are not responsible for any harmful consequences
 *    of using this software, even if they result from defects in it.
 */

UNIX is a trademark of AT&T (it used to be a trademark of Bell Labs)
Mark Williams C is a trademark of Mark Williams Company

AUTHORS

    original:
    Johann Ruegg      uunet!dunike!onecom!wldrdg!hans
    Don Dugger      uunet!dunike!onecom!wldrdg!n0ano
    modifications for version 1.2:
    Anthony Howe      [e-mail]
    Michal Jaegermann [e-mail]
    updates for versions 1.3, 1.4
    Michal Jaegermann [e-mail]